> 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/quickstart.md).

# Quickstart

Make your first on-chain agent payment in under five minutes.

***

## Prerequisites

* A Grand Protocol account at [app.grandprotocol.org](https://app.grandprotocol.org)

***

## Step 1: Get your API key

After signing in, go to **Settings → API Keys** in the dashboard and create an API key. Set it as an environment variable:

```bash
export GRAND_API_KEY=rp_live_...
```

***

## Step 2: Create an agent wallet

Every agent that makes payments needs a wallet. Wallets are non-custodial smart contract wallets on Robinhood Chain, controlled by the agent's signing key.

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

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

***

## Step 3: Fund the wallet

Top up via the dashboard at [app.grandprotocol.org](https://app.grandprotocol.org), or transfer USDC on Robinhood Chain directly to the wallet address shown above.

To check balance at any time:

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

```json
{
  "agentId": "my-agent",
  "balance": { "usdc": 50 }
}
```

***

## Step 4: Set spend policies

Policies are enforced at the gateway before any payment is submitted. Set them once.

```bash
curl -X PUT https://api.grandprotocol.org/v1/policies/my-agent \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dailyBudget": { "usdc": 10 },
    "perCallLimit": { "usdc": 0.50 },
    "allowedDomains": ["api.dune.com", "api.browserbase.com"]
  }'
```

***

## Step 5: Make your first payment

```bash
curl -X POST https://api.grandprotocol.org/v1/pay \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "my-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": { }
}
```

Grand Protocol detects the payment protocol automatically and handles the full handshake. You do not need to know whether the service uses x402 or MPP.

For production use, pass an `idempotencyKey` to prevent duplicate payments if your code retries a failed request:

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

If a payment with the same key already completed in the last 24 hours, Grand Protocol returns the cached result without charging again.

***

## Step 6: View the on-chain record

Every payment is recorded on Robinhood Chain. View your transaction history:

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

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

Click the transaction hash in the dashboard to open the Robinhood Chain explorer entry directly.

***

## Next steps

* [How the payment router works](/features/payment-router.md)
* [Agent wallet reference](/features/agent-wallets.md)
* [Full spend policy options](/features/spend-policies.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/quickstart.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.