> For the complete documentation index, see [llms.txt](https://docs.grandprotocol.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.grandprotocol.org/getting-started/your-first-payment.md).

# Your First Payment

This guide walks through the full lifecycle of making an agent payment with Grand Protocol: creating a wallet, setting spend policies, paying for an API service, and reading the on-chain record.

***

## Prerequisites

* A Grand Protocol account at [grandprotocol.org](https://grandprotocol.org)
* An API key from **Settings → API Keys**, exported as `GRAND_API_KEY`

If you haven't done this yet, the [Quickstart](/getting-started/quickstart.md) covers it in under five minutes.

***

## What we are building

An agent that:

* Holds its own non-custodial Robinhood Chain wallet
* Operates under a daily budget and a per-call spend limit
* Pays for a real data API call using x402
* Logs every payment to Robinhood Chain with a verifiable transaction hash

***

## 1. Create the wallet

```bash
curl -X POST https://api.grandprotocol.org/v1/wallets \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "research-agent" }'
```

```json
{
  "agentId": "research-agent",
  "address": "0x7A3f9C2E8b41D6a05F1c94E2B8D3a7C6e5F0b1A2",
  "balance": { "usdc": 0 },
  "network": "robinhood-mainnet"
}
```

The wallet is a smart contract wallet on Robinhood Chain, deployed deterministically from the agent ID. Only the agent's signing key can authorize payments from it. Grand Protocol cannot move funds without a validly signed transaction.

Fund the wallet by transferring USDC on Robinhood Chain to the address above, or via the dashboard at [app.grandprotocol.org](https://app.grandprotocol.org).

***

## 2. Set spend policies

Policies are checked at the gateway layer before any payment is submitted. A call that would breach the daily budget is rejected before funds leave the wallet.

```bash
curl -X PUT https://api.grandprotocol.org/v1/policies/research-agent \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dailyBudget": { "usdc": 25 },
    "perCallLimit": { "usdc": 1.00 },
    "allowedDomains": ["api.dune.com", "api.browserbase.com", "fal.ai"],
    "rateLimit": { "calls": 200, "window": "1h" }
  }'
```

Verify the policy is active:

```bash
curl https://api.grandprotocol.org/v1/policies/research-agent \
  -H "Authorization: Bearer $GRAND_API_KEY"
```

```json
{
  "agentId": "research-agent",
  "dailyBudget": { "usdc": 25 },
  "perCallLimit": { "usdc": 1.00 },
  "allowedDomains": ["api.dune.com", "api.browserbase.com", "fal.ai"],
  "rateLimit": { "calls": 200, "window": "1h" },
  "protocolPreference": "auto"
}
```

***

## 3. Make a payment

Call the REST API to make a payment:

```bash
curl -X POST https://api.grandprotocol.org/v1/pay \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "research-agent",
    "endpoint": "https://api.dune.com/v1/query/1234/results",
    "method": "GET"
  }'
```

```json
{
  "status": 200,
  "protocol": "x402",
  "amountPaid": { "usdc": 0.002 },
  "txHash": "0x5e9a3f...c41f",
  "data": { }
}
```

The gateway handles everything: reading the 402 response, constructing the payment payload, signing with the agent's wallet, and retrying the original request with payment attached. The API response comes back in `data` as if the payment never happened.

***

## 4. Handle policy rejections

If a call would exceed the spend policy, Grand Protocol rejects it before any funds are spent. The API returns a `402` with a structured error body:

```bash
curl -X POST https://api.grandprotocol.org/v1/pay \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "research-agent",
    "endpoint": "https://api.expensive-service.com/query",
    "method": "POST"
  }'
```

```json
{
  "error": "policy_violation",
  "reason": "per_call_limit_exceeded",
  "detail": "Requested 2.50 USDC, limit is 1.00 USDC"
}
```

Policy violations are also logged to the dashboard and can trigger webhook alerts.

***

## 5. View the on-chain record

List recent transactions for the agent:

```bash
curl "https://api.grandprotocol.org/v1/transactions?agentId=research-agent&limit=10" \
  -H "Authorization: Bearer $GRAND_API_KEY"
```

```json
{
  "transactions": [
    {
      "txHash": "0x5e9a3f...c41f",
      "protocol": "x402",
      "amountPaid": { "usdc": 0.002 },
      "endpoint": "api.dune.com/v1/query/1234/results",
      "timestamp": "2026-05-09T14:23:01Z"
    }
  ]
}
```

Inspect a single transaction:

```bash
curl https://api.grandprotocol.org/v1/transactions/0x5e9a3f...c41f \
  -H "Authorization: Bearer $GRAND_API_KEY"
```

```json
{
  "txHash": "0x5e9a3f...c41f",
  "agentId": "research-agent",
  "protocol": "x402",
  "amountPaid": { "usdc": 0.002 },
  "endpoint": "api.dune.com/v1/query/1234/results",
  "policyCheck": "passed",
  "parentTxHash": null,
  "explorerUrl": "https://robinhoodchain.blockscout.com/tx/0x5e9a3f...c41f",
  "timestamp": "2026-05-09T14:23:01Z"
}
```

The `explorerUrl` link goes to the public Robinhood Chain explorer entry for the transaction. The ledger is independent of Grand Protocol. Even if Grand Protocol went offline, your payment history would remain on-chain.

***

## 6. View the dashboard

The dashboard at [app.grandprotocol.org](https://app.grandprotocol.org) shows real-time spend, protocol split, policy events, and a live transaction feed with links to the Robinhood Chain explorer for every entry.

***

## Next steps

* [How the payment router selects protocols](/features/payment-router.md)
* [Full spend policy reference](/features/spend-policies.md)
* [Building multi-agent payment chains](/features/multi-agent-payments.md)
* [REST API reference](/platform/architecture.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.grandprotocol.org/getting-started/your-first-payment.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.