> ## Documentation Index
> Fetch the complete documentation index at: https://docs.droplinked.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic payments (x402)

> What an AI agent can pay for on Droplinked today — USDC on Base mainnet over the x402 protocol, the live challenge shape, the routes that exist, and the limits that are real.

Droplinked settles agent payments in **USDC on Base mainnet** using
[x402](https://x402.org), Coinbase's HTTP `402 Payment Required` micropayment protocol. The
gate is live on production: you can see a real challenge right now, without credentials.

USDC-on-Base is not an arbitrary pick. TRM Labs reports that **99.6% of settled x402 value
is USDC**, so a single asset on a single chain covers effectively the whole protocol's
volume — which is why Droplinked supports exactly that and does not ask an agent to hold
anything else.

## See it working

```bash theme={null}
curl -i https://apiv3.droplinked.com/feed/acp.premium.json
```

```http theme={null}
HTTP/2 402
x-payment-required: <base64 of the JSON body below>
```

```json theme={null}
{
  "scheme": "exact",
  "network": "base",
  "maxAmountRequired": "1000",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "payTo": "0x…",
  "resource": "https://apiv3.droplinked.com/feed/acp.premium.json",
  "description": "droplinked premium ACP product feed — per-call micro-payment",
  "mimeType": "application/json",
  "outputSchema": {},
  "extra": { "name": "USD Coin", "version": "2", "currency": "USDC" }
}
```

| Field | Value |
| - | - |
| Network | Base **mainnet** |
| Asset | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` — Circle's USDC on Base |
| Scheme | `exact` |
| Amount | `1000` atomic units — USDC has 6 decimals, so \$0.001 |
| Settlement primitive | EIP-3009 `transferWithAuthorization`, verified through the Coinbase CDP facilitator |

`payTo` is returned live in the challenge — read it from the response rather than
hard-coding it.

## Signing correctly

`extra.name` and `extra.version` are the **EIP-712 domain** the transfer authorisation must
be signed over. Sign against the domain the challenge gives you (`name: "USD Coin"`,
`version: "2"`). Two failure modes that look like bugs and are not:

* A signature produced over a different domain will not verify.
* A plain USDC transfer that skips the authorisation is **not** a payment proof. x402 needs
  the signed authorisation, not the transfer.

Then re-request with the serialised proof in the `X-PAYMENT` header.

## What an agent can do today

### Discover and read inventory — free, no credentials

Droplinked runs a public MCP server. Read tools are open; no key, no account.

| Surface | Tools |
| - | - |
| `https://mcp.droplinked.com/mcp` (streamable HTTP, stateless) | 38 tools — merchant and inventory discovery, trust-fabric verification, cart composition, lending |
| `https://apiv3.droplinked.com/mcp/v1` | 11 read tools including `searchProducts`, `findInventory`, `getProductDetail`, `getShopInfo`, `listMerchants`, `searchMerchants`, `getMerchantDirectory`, `getMerchantCatalogSummary`, `getInventoryHealth`, `getStockoutAlerts` |

Manifest: `https://mcp.droplinked.com/.well-known/mcp.json`. Send
`Accept: application/json, text/event-stream` on JSON-RPC calls. Write tools require
`X-MCP-API-Key` when the server is key-gated.

```bash theme={null}
curl -sS -X POST https://apiv3.droplinked.com/mcp/v1/tools/call \
  -H 'content-type: application/json' \
  -d '{"name":"searchProducts","arguments":{"query":"shirt","limit":2}}'
```

That returns real production catalog rows.

### Pay an x402-gated resource

The premium feed endpoint above is a working reference implementation of the full
handshake. See [x402 Premium ACP Feed](/agentic/x402-premium-feed.md) — **including what its
payload does and does not contain today.**

### Order-level x402 routes

These are mounted and authenticated. They are the checkout-side rails, and they are the
part of the stack most likely to change, so confirm current behaviour with us before you
build against them:

| Route | Caller |
| - | - |
| `POST /v2/orders/:orderId/x402-pay` | The owning buyer or merchant. Returns `402` with the payment descriptor when `X-PAYMENT` is absent; settles and confirms the order when it is present and valid. |
| `POST /v2/agentic/orders/:orderId/x402-settle` | A consumer agent. The agent analogue of the route above. The signed payment binds to this path, so a proof minted for `/x402-pay` will not verify here — the resource in the challenge is the path you must sign for. |

### Platform metering

| Route | Purpose |
| - | - |
| `POST /platform-billing/x402/quote` | Quote a metered platform call |
| `POST /platform-billing/x402/settle` | Settle it |
| `GET /platform-billing/x402/credits` | Read remaining credits |
| `GET /platform-billing/metered/ping` | Metering reachability check |

## Limits you should know before you design around this

> [!WARNING]
>
> **A merchant cannot currently be paid in USDC.** x402 settles to the platform. There is no
> merchant-owned x402 payout destination configured today, so there is no merchant
> settlement leg to route to. Treat x402 on Droplinked as a **platform and agent-surface
> payment rail**, not as a merchant payout rail. Anything describing turnkey stablecoin
> settlement for merchants is roadmap.

* **Rate limits still apply to `402` responses.** The premium feed carries
  `x-ratelimit-limit: 60` like any other endpoint — paying per call does not exempt you
  from the request budget. See [Rate limits](/api-reference/rate-limits.md).
* **Base mainnet only.** No testnet path is published, so there is no free way to exercise
  the full handshake end to end. Budget real (if tiny) USDC for integration testing.

## Failure modes

| Response | Meaning | What to do |
| - | - | - |
| `402` | First call, or an invalid/absent proof. Body is the descriptor. | Sign and retry with `X-PAYMENT`. |
| `503` `X402_NOT_CONFIGURED` | No facilitator configured on this environment. | Surface to the operator. Do not retry. |
| `503` `X402_FACILITATOR_UNAVAILABLE` | Facilitator unreachable or its circuit breaker is open. | Exponential backoff. |
| `400` `X402_ORDER_NOT_CONFIRMABLE` | Order is not in a payable state. | Do not retry; re-read the order. |
| `400` `X402_SETTLE_FAILED` | Facilitator rejected settlement; reason appended. | Re-sign with a fresh nonce. |

## Related

* [x402 Premium ACP Feed](/agentic/x402-premium-feed.md)
* [Consume the Droplinked MCP](/agentic/consume-droplinked-mcp.md)
* [Errors](/api-reference/errors.md)
* [x402 protocol spec](https://x402.org)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.