Hosted REST API
Receiving
The merchant's pay_to destination(s). Validated loud and early at write time so an agent never hits a broken receiving config at runtime.
receiving is where settled money goes — the pay_to an agent reads from the manifest. It
is validated at write time (POST/PATCH /v1/merchants, PUT /v1/receiving) so a broken
destination fails for the merchant, never for the agent mid-checkout.
Shape
{
"receiving": {
"x402": { "chain": "base", "address": "0x…", "asset": "USDC" },
"card": { "processor": "stripe", "accountId": "acct_…" },
"mock": { "account": "test-sink" }
}
}At least one rail must be enabled and configured. Supported chains/assets mirror the SDK
token registry: USDC on base and base-sepolia.
| Rail | Required fields | Notes |
|---|---|---|
x402 | chain, address | address is a 20-byte 0x hex address; asset defaults to USDC. |
card | processor, accountId | Typed stub (not load-bearing in v1). |
mock | account | Test mode only — never valid on a live merchant. |
Validation reason codes
| Code | Cause |
|---|---|
RECEIVING_RAIL_UNKNOWN | A key other than x402 / card / mock. |
RECEIVING_ADDRESS_INVALID | Missing field, or an x402 address that isn't 20-byte 0x hex. |
RECEIVING_CHAIN_UNSUPPORTED | Chain not base / base-sepolia. |
RECEIVING_ASSET_UNKNOWN | (chain, asset) not in the token registry. |
RECEIVING_NO_RAIL_ENABLED | Zero configured rails. |
RECEIVING_MOCK_IN_LIVE | mock rail set on a live merchant. |
GET /v1/receiving
Show the resolved merchant's receiving config and enabled rails.
| Auth | API key · scope merchants:read |
|---|---|
| Query | merchant_id (optional) |
{
"receiving": { "x402": { "chain": "base", "address": "0x…", "asset": "USDC" } },
"rails": ["x402", "mock"]
}PUT /v1/receiving
Replace the receiving config. Validated against the table above; on success the manifest cache is invalidated.
| Auth | API key · scope merchants:write |
|---|
{ "receiving": { "x402": { "chain": "base", "address": "0x1111111111111111111111111111111111111111", "asset": "USDC" } } }| Status | Reason code | Meaning |
|---|---|---|
200 | — | { "receiving": { … } } (normalized). |
400 | any receiving code above | Validation failed. |
404 | NOT_FOUND | Merchant not found in this project/mode. |
curl -X PUT "https://api.veto-ai.com/v1/receiving?merchant_id=mrch_01J…" \
-H "Authorization: Bearer veto_test_8f2c…" \
-H "Content-Type: application/json" \
-d '{ "receiving": { "x402": { "chain": "base-sepolia", "address": "0x1111111111111111111111111111111111111111" } } }'