# API: resource on an address with a key

> Order Energy and Bandwidth on any TRON address from your code: API key, quote, order, status.

Your code orders Energy and Bandwidth on any TRON address through the same API the cabinet runs on. A Direct order
keeps the resource on the address for 1000 blocks (≈ 50 minutes); the price is fixed by a quote before the order; the
organization's balance pays.

| | |
|---|---|
| API address | `https://cabinet-api.awesomefee.com/api/v1` |
| Key | header `X-API-Key`, or `Authorization: Bearer` with an OAuth token |
| Organization | `org_…` in the path of every request |
| Bodies | JSON |

## Step 0. In the cabinet (a person, once)

1. Sign in to the [cabinet](https://app.awesomefee.com/en/app) and top up the balance of the organization.
2. "API keys" → "Create key". Orders need the `write` scope, reading needs `read`. The secret is shown once.
3. The same screen shows the organization ID (`org_…`) and the API address, each with a copy button.

Give the key and the organization ID to your code (or your coding assistant) as `KEY` and `ORG`.

**An AI agent without a key** can get access by OAuth instead: it registers with your email, shows you a 6-digit code,
you type it in the cabinet and pick the organization and the scopes. Apps and MCP clients use the authorization code
flow with PKCE. Both are described in [auth.md](/auth.md); the access appears among your API keys marked "agent" and is
revoked there. A key can also be exchanged for a bearer token: `POST https://cabinet-api.awesomefee.com/api/v1/oauth/token` with
`grant_type=client_credentials&client_secret=$KEY`.

## Step 1. Quote

The price of the amount for 1000 blocks. A quote is valid for 30 seconds. `resource` is `ENERGY` or `BANDWIDTH`.

```bash
curl -s -X POST "https://cabinet-api.awesomefee.com/api/v1/orgs/$ORG/quotes" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","resource":"ENERGY","amount":65000}'
```

Answer: `quote_id`, `price_sun` and `price_trx`, `available`, `expires_at`.

## Step 2. Order

The body of the quote plus `quote_id`. The `Idempotency-Key` header is required: a repeat with the same key returns
the same order (`200`).

```bash
curl -s -X POST "https://cabinet-api.awesomefee.com/api/v1/orgs/$ORG/orders" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-11-16-0001" \
  -d '{"quote_id":"qt_…","address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","resource":"ENERGY","amount":65000}'
```

`202` — the order is accepted: `order_id`, `status: ACCEPTED`.

## Step 3. Status

```bash
curl -s "https://cabinet-api.awesomefee.com/api/v1/orgs/$ORG/orders/$ORDER" -H "X-API-Key: $KEY"
```

`ACCEPTED` → `PROVISIONING` → `DELIVERED`: the resource is on the address and the transaction goes out with no TRX
burned. `PARTIAL` — part of the amount delivered; `FAILED` — nothing delivered, nothing charged. The steps of the
order with txids: `GET /orgs/$ORG/orders/$ORDER/events`.

## Resource on your addresses, always: Mate

For a constant flow, put the addresses into Mate:

- `POST /orgs/{orgId}/addresses` — add an address: `{"address":"T…","label":"payouts"}`;
- `PUT /orgs/{orgId}/addresses/{address}/scenario` — the mode: `{"mode":"watch"}` or `{"mode":"serve"}`;
- `GET /orgs/{orgId}/addresses/{address}/usage` — consumption by hour; `…/burns` — TRX burned; `…/delegations` —
  our delegations on the address.

## Other calls with a key

- `GET /orgs/{orgId}/orders` — orders with filters; `GET /orgs/{orgId}/orders/export.csv`.
- `GET /orgs/{orgId}/orders/{id}/reclaim-preview`, `POST /orgs/{orgId}/orders/{id}/reclaim` — early reclaim.
- `GET /orgs/{orgId}/balance`, `GET /orgs/{orgId}/balance/history`.
- `GET /tron/addresses/{address}/check`, `GET /tron/addresses/{address}/preview` — any address: format, activation,
  live resources, TRX burned in 24 h.
- `GET /orgs/{orgId}/api-limits`, `GET /orgs/{orgId}/api-usage` — the limits and the use of the key.

## Errors

An error is JSON `{"error":"<message>","code":"<CODE>"}` with the HTTP status:

| Status | Codes |
|---|---|
| 400 | `VALIDATION_ERROR`, `INVALID_ADDRESS`, `AMOUNT_BELOW_MIN`, `DURATION_FIXED` (Direct: 1000 blocks only) |
| 401 | no key, a revoked or expired key |
| 402 | `INSUFFICIENT_BALANCE` |
| 403 | `FORBIDDEN_ROLE` (the key's scope), `ADDRESS_NOT_ALLOWED` |
| 409 | `QUOTE_EXPIRED`, `IDEMPOTENCY_CONFLICT`, `NOT_RECLAIMABLE` |
| 429 | the key's limit; wait `Retry-After` |
| 503 | `NO_CAPACITY`, `UPSTREAM_UNAVAILABLE`; retry after `Retry-After` |

Without an account, paying per call in USDC: [AI agents and x402](/docs/en/agents/overview/).
