# Your First Payment

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

***

## What we are building

An agent that:

* Holds its own non-custodial Solana 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 Solana with a verifiable transaction hash

***

## 1. Create the wallet

```bash
grace wallet create --agent research-agent
```

```
Agent wallet created.

  Agent:    research-agent
  Address:  7xKXtg2xpAGMq8KLwpSodE9LFKq8Z1EscezSShpump
  Balance:  0.00 USDC
  Network:  Solana Mainnet
```

The wallet is a program-derived address (PDA) on Solana. Only the agent's keypair can authorize payments from it. Grace Protocol cannot move funds without a valid signed instruction.

Fund the wallet by transferring USDC to the address above, or via the dashboard at [app.graceprotocol.org](https://app.graceprotocol.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
grace policies set research-agent \
  --daily-budget 25 \
  --per-call-limit 1.00 \
  --allowed-domains "api.dune.com,api.browserbase.com,fal.ai" \
  --rate-limit "200 per hour"
```

Verify the policy is active:

```bash
grace policies get research-agent
```

```
Agent:           research-agent
Daily budget:    25.00 USDC
Per-call limit:  1.00 USDC
Allowed domains: api.dune.com, api.browserbase.com, fal.ai
Rate limit:      200 / hour
Protocol pref:   auto (x402 preferred)
```

***

## 3. Make a payment

Call the REST API to make a payment:

```bash
curl -X POST https://api.graceprotocol.org/v1/pay \
  -H "Authorization: Bearer $GRACE_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": "5yJ8kXtg2xp...mQ9pL",
  "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, Grace Protocol rejects it before any funds are spent. The API returns a `402` with a structured error body:

```bash
curl -X POST https://api.graceprotocol.org/v1/pay \
  -H "Authorization: Bearer $GRACE_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
grace transactions list --agent research-agent --limit 10
```

```
TX HASH                      PROTOCOL  AMOUNT      ENDPOINT                                  TIME
5yJ8kXtg2xp...mQ9pL         x402      0.002 USDC  api.dune.com/v1/query/1234/results        2 min ago
```

Inspect a single transaction:

```bash
grace transactions inspect 5yJ8kXtg2xp...mQ9pL
```

```
Transaction: 5yJ8kXtg2xp...mQ9pL
Agent:       research-agent
Protocol:    x402
Amount:      0.002 USDC
Endpoint:    api.dune.com/v1/query/1234/results
Policy:      passed
Solana:      https://explorer.solana.com/tx/5yJ8kXtg2xp...mQ9pL
Timestamp:   2026-05-09T14:23:01Z
```

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

***

## 6. View the dashboard

The dashboard at [app.graceprotocol.org](https://app.graceprotocol.org) shows real-time spend, protocol split, policy events, and a live transaction feed with links to Solana 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: 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/your-first-payment.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.