# Quickstart

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

***

## Prerequisites

* A Grace Protocol account at [app.graceprotocol.org](https://app.graceprotocol.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 GRACE_API_KEY=rp_live_...
```

***

## Step 2: Create an agent wallet

Every agent that makes payments needs a wallet. Wallets are non-custodial Solana program-derived addresses owned by the agent's keypair.

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

```json
{
  "agentId": "my-agent",
  "address": "7xKXtg2xpAGMq8KLwpSodE9LFKq8Z1EscezSShpump",
  "balance": { "usdc": 0 },
  "network": "solana-mainnet"
}
```

***

## Step 3: Fund the wallet

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

To check balance at any time:

```bash
curl https://api.graceprotocol.org/v1/wallets/my-agent \
  -H "Authorization: Bearer $GRACE_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.graceprotocol.org/v1/policies/my-agent \
  -H "Authorization: Bearer $GRACE_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.graceprotocol.org/v1/pay \
  -H "Authorization: Bearer $GRACE_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": "5yJ8kX...mQ9pL",
  "data": { }
}
```

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

***

## Step 6: View the on-chain record

Every payment is recorded on Solana. View your transaction history:

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

```json
{
  "transactions": [
    {
      "txHash": "5yJ8kX...mQ9pL",
      "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 Solana 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: 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:

```
GET https://docs.graceprotocol.org/getting-started/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.