> For the complete documentation index, see [llms.txt](https://docs.robotmoney.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.robotmoney.com/govern/purchase-execution-api.md).

# Purchase Execution

Execute an approved purchase on Base Sepolia and read settlement proof.

Purchase execution turns one approved purchase decision into one bound Base Sepolia settlement command. The command rechecks the current policy, grant, merchant risk, balance, and approval state before the worker can contact the provider.

## Availability

| Capability                                     | Status                   |
| ---------------------------------------------- | ------------------------ |
| Record purchase decisions and budget drawdowns | **Live**                 |
| Base Sepolia x402 purchase execution           | **Sandbox, default off** |
| Production purchase execution                  | **Planned after pilots** |
| Card purchase execution                        | **Planned**              |
| Base mainnet purchase execution                | **Planned**              |

The execution flag remains off in every environment. The staging smoke workflow is present but has not run. It needs fresh approval before one staging run. Production OpenSanctions remains off through the pilots.

## Execute An Approved Decision

```http
POST /v1/purchases/{decision_id}/execute
Authorization: Bearer <purchase executor token>
Idempotency-Key: example
Content-Type: application/json
```

```json
{
  "pay_to": "0x1111111111111111111111111111111111111111"
}
```

The token must come from a server-owned `purchase_executor` agent-key profile and carries only `purchase:execute`. Member and owner tokens never receive this scope. The scope can start a command bound to an approved decision. It cannot approve or dispatch a payment.

The supplied address must match the recipient approved on the purchase decision. The execution also binds the agent, merchant, country, category, currency, amount, grant, drawdown, source wallet, policy decision, Base Sepolia chain, and fee quote. Reusing the same idempotency key with the same binding returns the original execution. Any changed binding returns a conflict.

The execute call does not add another authorization usage unit. The original row in `purchase_decision_billing` remains the authorization billing record.

## Read Settlement State

```http
GET /v1/purchases/{decision_id}/execution
Authorization: Bearer <purchase executor token>
```

Before provider creation, `status` is absent. Once provider creation may have started, status is `submitted`. Clients should poll with bounded backoff and act only when status is `settled`.

```json
{
  "purchase_decision_id": "pdec_...",
  "purchase_execution_id": "pexec_...",
  "payment_intent_id": "pi_...",
  "status": "settled",
  "execution_fee_status": "settled",
  "fee_quote": {
    "recipient_amount": "40.000000",
    "fee_amount": "0.100000",
    "total_debit": "40.100000",
    "asset": "USDC",
    "chain": "eip155:84532",
    "fee_policy_revision": 1,
    "quote_hash": "...",
    "quote_expires_at": "2026-10-25T12:15:00.000Z"
  },
  "approval_required": false,
  "failure_code": null,
  "settlement_proof": {
    "chain": "eip155:84532",
    "principal": {
      "ledger_transaction_id": "txn_...",
      "transaction_hash": "0x...",
      "explorer_url": "https://sepolia.basescan.org/tx/0x..."
    },
    "fee": {
      "ledger_transaction_id": "txn_...",
      "transaction_hash": "0x...",
      "explorer_url": "https://sepolia.basescan.org/tx/0x..."
    },
    "charge": {
      "charge_fact_id": "chf_...",
      "status": "finalized"
    }
  },
  "created_at": "2026-10-25T12:00:00.000Z"
}
```

Settlement proof comes from independently verified canonical Base Sepolia receipts and linked Ledger transactions. A provider success response alone is not settlement proof.

## Fee And Approval

The purchase fee is 25 basis points of the principal as a separate fee leg. The existing 0.1 USDC minimum applies, so the effective fee is above 0.25 percent for purchases under 40 USDC. An optional catalog maximum applies when configured.

The worker settles the principal first, then the fee. A valid permanent fee waiver can settle the purchase after the principal. A terminal fee failure does not reverse a settled principal.

Autonomous settlement requires an active signed policy with both `onchain_settlement_permitted: true` and a covering `x402_autonomous_max_amount`. Otherwise a human approval is required. The fee quote freezes when approval starts and expires after 15 minutes. An expiry before provider creation releases the exact budget drawdown once and requires a new purchase decision.

## Merchant And Failure Checks

Execution reruns sanctions, policy, grant, agent, recipient, duplicate, and balance checks. Only a clear merchant screening result allows an unresolved merchant. Missing configuration, an unavailable or stale screening result, a changed merchant, a revoked grant, or a failed Section 6 gate blocks before provider creation.

A proven pre-provider failure releases the exact drawdown once. If the provider may have been called, the drawdown stays held for audited operator review. Raw provider payloads and raw sanctions payloads are never retained.

## Activity, Webhooks, Usage, And MCP

Activity rows keep `type: purchase` and can include the execution id, fee status, finalized transaction link, charge fact id, and bounded failure reason.

Webhook endpoints can subscribe to:

* `purchase.execution.submitted`
* `purchase.execution.settled`
* `purchase.execution.failed`
* `purchase.execution.escalated`

`GET /v1/usage/authorizations` continues to count only the original purchase decision billing row. Settlement and webhook lifecycle events do not add usage decisions.

MCP clients can read the same customer-safe projection at:

```
brain://purchases/{decision_id}/execution
```

The resource requires `purchase:execute` and applies the same tenant and owning agent isolation as the HTTP read.

## Related APIs

* [Purchase Decisions API](https://docs.robotmoney.com/govern/purchase-decisions-api.md)
* [Usage API](https://docs.robotmoney.com/govern/usage-api.md)
* [Webhooks](https://docs.robotmoney.com/api-reference/webhooks-api.md)
* [MCP Server API](https://docs.robotmoney.com/api-reference/mcp-server-api-reference.md)
