{ "openapi": "3.1.0", "info": { "title": "Agent Value Network local payment API", "version": "0.1.0", "description": "Noncustodial local prototype. No keys, custody, broadcasting, public service or economic finality. Token amounts are positive, capped at 1000 and represented with 18 decimals. Sender wallet signs typed data externally and broadcasts the returned transaction. Supports contract-wallet signatures through token static-call verification. RPC and token are selected only by local deployment configuration. Local Host/Origin restriction, 16 KiB bodies, 120 requests/minute. Fee quote is for direct ERC20 transfer; authorization gas may differ." }, "servers": [ { "url": "http://127.0.0.1:18741", "description": "Loopback-only local API" } ], "paths": { "/healthz": { "get": { "description": "Checks configured chain, deployed token bytecode and token identity.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "400": { "description": "Invalid fields, addresses, amounts, authorization or JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host or Origin is not local.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Fee estimation, authorization simulation or receipt token check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests per socket address per minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Deployment, identity, chain or configured RPC unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/agent-payments.json": { "get": { "description": "Local capabilities with relative API base. Does not advertise a public endpoint.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discovery" } } } }, "400": { "description": "Invalid fields, addresses, amounts, authorization or JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host or Origin is not local.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Fee estimation, authorization simulation or receipt token check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests per socket address per minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Deployment, identity, chain or configured RPC unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payments/prepare": { "post": { "description": "Creates a random 32-byte nonce and active authorization with expiry in 1 to 300 seconds. maxAmount can lower the 1000-token limit. Direct transfer fee estimation must succeed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareResponse" } } } }, "400": { "description": "Invalid fields, addresses, amounts, authorization or JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host or Origin is not local.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Fee estimation, authorization simulation or receipt token check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests per socket address per minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Deployment, identity, chain or configured RPC unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payments/encode": { "post": { "description": "Checks deployment domain, value and active 300-second authorization window, then simulates the exact token authorization against the pending local block. Returns unsigned calldata; caller wallet chooses the broadcaster and pays gas. Never sends a transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncodeRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncodeResponse" } } } }, "400": { "description": "Invalid fields, addresses, amounts, authorization or JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host or Origin is not local.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Fee estimation, authorization simulation or receipt token check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests per socket address per minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Deployment, identity, chain or configured RPC unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/receipts/{hash}": { "get": { "description": "Reports pending, reverted or a successful receipt with at least one matching token Transfer log. Confirmation count is local block depth, not economic finality.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "Invalid fields, addresses, amounts, authorization or JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host or Origin is not local.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Fee estimation, authorization simulation or receipt token check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests per socket address per minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Deployment, identity, chain or configured RPC unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } ] } } }, "components": { "schemas": { "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Domain": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "version": { "type": "string", "const": "1" }, "chainId": { "type": "number", "const": 20261008 }, "verifyingContract": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "Message": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "value": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Gross token debit in base units. Net recipient leg = value - floor(value/100). Tax leg goes to the immutable treasury." }, "validAfter": { "type": "integer", "minimum": 0 }, "validBefore": { "type": "integer", "minimum": 1 }, "nonce": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "required": [ "from", "to", "value", "validAfter", "validBefore", "nonce" ] }, "Types": { "type": "object", "additionalProperties": false, "properties": { "TransferWithAuthorization": { "type": "array", "minItems": 6, "maxItems": 6, "prefixItems": [ { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "const": "from" }, "type": { "type": "string", "const": "address" } }, "required": [ "name", "type" ] }, { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "const": "to" }, "type": { "type": "string", "const": "address" } }, "required": [ "name", "type" ] }, { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "const": "value" }, "type": { "type": "string", "const": "uint256" } }, "required": [ "name", "type" ] }, { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "const": "validAfter" }, "type": { "type": "string", "const": "uint256" } }, "required": [ "name", "type" ] }, { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "const": "validBefore" }, "type": { "type": "string", "const": "uint256" } }, "required": [ "name", "type" ] }, { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "const": "nonce" }, "type": { "type": "string", "const": "bytes32" } }, "required": [ "name", "type" ] } ], "items": false } }, "required": [ "TransferWithAuthorization" ] }, "TypedData": { "type": "object", "additionalProperties": false, "properties": { "domain": { "$ref": "#/components/schemas/Domain" }, "types": { "$ref": "#/components/schemas/Types" }, "primaryType": { "type": "string", "const": "TransferWithAuthorization" }, "message": { "$ref": "#/components/schemas/Message" } }, "required": [ "domain", "types", "primaryType", "message" ] }, "PrepareRequest": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,18})?$", "description": "Gross MTR amount including the 1% deducted treasury tax, not the recipient net amount." }, "maxAmount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,18})?$", "description": "Maximum gross MTR amount the caller permits." }, "ttlSeconds": { "type": "integer", "minimum": 1, "maximum": 300, "default": 300 } }, "required": [ "from", "to", "amount" ] }, "Details": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,18})?$" }, "symbol": { "type": "string" }, "expiresAt": { "type": "integer" }, "network": { "type": "string", "const": "local-devnet" }, "warning": { "type": "string" }, "amountSemantics": { "type": "string", "const": "gross" }, "grossAmount": { "type": "string" }, "recipientAmount": { "type": "string", "description": "Net transfer leg; if recipient is the treasury it also receives the tax leg." }, "treasuryTaxAmount": { "type": "string" }, "transferTaxBps": { "type": "integer", "const": 100 }, "treasury": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "required": [ "from", "to", "amount", "symbol", "expiresAt", "network", "warning", "amountSemantics", "grossAmount", "recipientAmount", "treasuryTaxAmount", "transferTaxBps", "treasury" ] }, "FeeQuote": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "const": "direct-erc20-transfer-estimate" }, "gas": { "type": "string", "pattern": "^[0-9]+$" }, "maxFeePerGas": { "type": "string", "pattern": "^[0-9]+$" }, "estimatedNativeFee": { "type": "string", "pattern": "^[0-9]+$" }, "nativeUnit": { "type": "string", "const": "wei" }, "authorizationExecutionMayDiffer": { "type": "boolean", "const": true } }, "required": [ "kind", "gas", "maxFeePerGas", "estimatedNativeFee", "nativeUnit", "authorizationExecutionMayDiffer" ] }, "PrepareResponse": { "type": "object", "additionalProperties": false, "properties": { "typedData": { "$ref": "#/components/schemas/TypedData" }, "details": { "$ref": "#/components/schemas/Details" }, "feeQuote": { "$ref": "#/components/schemas/FeeQuote" } }, "required": [ "typedData", "details", "feeQuote" ] }, "EncodeRequest": { "type": "object", "additionalProperties": false, "properties": { "typedData": { "$ref": "#/components/schemas/TypedData" }, "signature": { "type": "string", "pattern": "^0x([0-9a-fA-F]{2})+$", "maxLength": 8194 } }, "required": [ "typedData", "signature" ] }, "Transaction": { "type": "object", "additionalProperties": false, "properties": { "to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "data": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" }, "value": { "type": "string", "const": "0" }, "chainId": { "type": "number", "const": 20261008 } }, "required": [ "to", "data", "value", "chainId" ] }, "EncodeResponse": { "type": "object", "additionalProperties": false, "properties": { "transaction": { "$ref": "#/components/schemas/Transaction" }, "broadcast": { "type": "boolean", "const": false } }, "required": [ "transaction", "broadcast" ] }, "Transfer": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,18})?$" }, "value": { "type": "string", "pattern": "^[0-9]+$" }, "symbol": { "type": "string" } }, "required": [ "from", "to", "amount", "value", "symbol" ] }, "Health": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "const": "ok" }, "chainId": { "type": "number", "const": 20261008 }, "tokenAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "network": { "type": "string", "const": "local-devnet" }, "economicFinality": { "type": "boolean", "const": false } }, "required": [ "status", "chainId", "tokenAddress", "network", "economicFinality" ] }, "Discovery": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "string", "const": "1" }, "network": { "type": "string", "const": "local-devnet" }, "chainId": { "type": "number", "const": 20261008 }, "token": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number", "const": 18 }, "amountSemantics": { "type": "string", "const": "gross" }, "transferTaxBps": { "type": "integer", "const": 100 }, "treasury": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "required": [ "address", "name", "symbol", "decimals", "transferTaxBps", "treasury", "amountSemantics" ] }, "apiBase": { "type": "string", "const": "/v1" }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "prepare-authorization", "encode-unsigned-transaction", "local-receipt" ] }, "minItems": 3, "maxItems": 3 }, "custody": { "type": "boolean", "const": false }, "broadcasts": { "type": "boolean", "const": false }, "economicFinality": { "type": "boolean", "const": false } }, "required": [ "version", "network", "chainId", "token", "apiBase", "capabilities", "custody", "broadcasts", "economicFinality" ] }, "Receipt": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "network": { "type": "string", "const": "local-devnet" }, "economicFinality": { "type": "boolean", "const": false }, "status": { "type": "string", "const": "pending" } }, "required": [ "hash", "network", "economicFinality", "status" ] }, { "type": "object", "additionalProperties": false, "properties": { "hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "network": { "type": "string", "const": "local-devnet" }, "economicFinality": { "type": "boolean", "const": false }, "status": { "type": "string", "const": "reverted" } }, "required": [ "hash", "network", "economicFinality", "status" ] }, { "type": "object", "additionalProperties": false, "properties": { "hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "network": { "type": "string", "const": "local-devnet" }, "economicFinality": { "type": "boolean", "const": false }, "status": { "type": "string", "const": "confirmed" }, "blockNumber": { "type": "integer", "minimum": 0 }, "confirmations": { "type": "integer", "minimum": 0 }, "transfers": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Transfer" } }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/TaxedPayment" } } }, "required": [ "hash", "network", "economicFinality", "status", "blockNumber", "confirmations", "transfers", "payments" ] } ] }, "TaxedPayment": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "gross": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "treasury": { "type": "string" } }, "required": [ "from", "to", "gross", "net", "tax", "treasury" ] } } } }