> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Redes X402 e Métodos de Pagamento

> Platform API guide - Ace Data Cloud

O Ace Data Cloud X402 atualmente realiza liquidação em torno de USDC, oferecendo suporte a dois tipos de redes: EVM e Solana. Os métodos de assinatura, endereços de ativos, comportamentos de gas e cenários aplicáveis diferem entre as redes, portanto, é necessário escolher a rede antes da integração.

## Os Identificadores de Rede Usam CAIP-2

O `accepts[].network` do x402 v2 é um identificador CAIP-2, não uma abreviação como `base` ou `skale`. Ao corresponder redes, o cliente deve comparar pelas strings CAIP-2:

| Rede | Identificador CAIP-2 |
| - | - |
| Base | `eip155:8453` |
| SKALE Base | `eip155:1187947933` |
| Solana mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` |

## Matriz de Suporte

| Rede | scheme | Ativo | Método de Assinatura | Cenário Aplicável |
| - | - | - | - | - |
| Base | `exact` | Base USDC | EIP-3009 `TransferWithAuthorization` | Recomendado por padrão, com suporte maduro de carteiras e liquidez. |
| Base | `upto` | Base USDC + Permit2 | Permit2 `PermitWitnessTransferFrom` | APIs de medição posterior, como chat e modelos. |
| SKALE | `exact` | SKALE bridged USDC | EIP-3009 `TransferWithAuthorization` | Baixo custo de gas, adequado para verificação de pagamentos EVM e chamadas de baixo custo. |
| Solana | `exact` | Solana USDC | SPL `TransferChecked` | Cenários de carteiras Solana, Agents ou aplicações on-chain. |

Atualmente, `upto` é fornecido apenas na Base. Os itens realmente disponíveis devem seguir o `accepts` retornado pela API. Você também pode consultar o Facilitator:

```bash theme={null}
curl https://facilitator.acedata.cloud/supported
```

O retorno do Facilitator `/supported`:

```json theme={null}
{
  "kinds": [
    { "x402Version": 2, "scheme": "exact", "network": "eip155:8453" },
    {
      "x402Version": 2,
      "scheme": "upto",
      "network": "eip155:8453",
      "extra": { "facilitatorAddress": "0xd019238EAA8a9Ca13C5792Ca10B4029D6ce25708" }
    },
    { "x402Version": 2, "scheme": "exact", "network": "eip155:1187947933" },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "extra": { "feePayer": "3SPm6qbgsDkj24MuR8Ss4sH97fziqyCiqFKDyeVU2igq" }
    }
  ]
}
```

Explicação dos resultados:

* O `exact` de Base, SKALE e Solana é um caminho de pagamento de valor fixo.
* Apenas a Base fornece o caminho de medição posterior `upto`, que depende da aprovação Permit2.
* O `extra.facilitatorAddress` na entrada `upto` é o endereço que o cliente deve escrever no witness ao assinar e deve ser consistente com o valor retornado pelo servidor.

## Base

A Base usa o contrato oficial de USDC:

```text theme={null}
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
```

No esquema `exact`, o cliente assina o EIP-712 `TransferWithAuthorization`. O conteúdo da assinatura inclui:

* `from`: endereço da carteira pagadora
* `to`: endereço recebedor do Ace Data Cloud
* `value`: valor deste pagamento
* `validAfter` / `validBefore`: janela de validade da assinatura
* `nonce`: nonce aleatório de 32 bytes

Após verificar a assinatura, o Facilitator chamará `transferWithAuthorization` do USDC on-chain para concluir a transferência.

A Base é a rede mais recomendada para integração formal, especialmente adequada para a medição posterior `upto`, pois os ecossistemas de Permit2, USDC e carteiras são mais maduros.

Exemplo de resultado de verificação Base `exact`:

```text theme={null}
payer 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105
content ADC_BASE_E2E_OK
tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
block 46726299
explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
transfer value 95215 atomic USDC
```

Explicação dos resultados:

* A nova tentativa paga da API retorna o conteúdo do modelo `ADC_BASE_E2E_OK`.
* A transação on-chain pode ser consultada no BaseScan, e o número do bloco é `46726299`.
* `95215` USDC atômicos correspondem a `0.095215` USDC, que é o valor real liquidado desta chamada de API.

Resultado da execução do programa de pagamento de pedido Base `exact`:

```text theme={null}
order 78481793-304e-47f7-bc0c-8231aec9cc1e
state Finished
tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
block 46726704
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
transfer value 1200000 atomic USDC
```

Explicação dos resultados:

* O estado final do pedido na plataforma é `Finished`.
* O `pay_id` do pedido grava o mesmo hash de transação Base.
* `1200000` USDC atômicos correspondem a `1.2` USDC, que é o valor histórico efetivamente pago deste pedido de 10 Credits sob a política antiga; novos pedidos não recebem mais desconto adicional pelo método de pagamento X402, e o valor específico da assinatura deve seguir a resposta 402 desta vez.

## SKALE

A SKALE usa USDC bridged, e o método de assinatura é semelhante ao da Base, também sendo EIP-3009. Ela é adequada para cenários de pagamento EVM com baixo custo de gas; as chamadas reais ainda devem seguir o `accepts` retornado pela API.

O `accepts` 402 típico da SKALE incluirá:

```json theme={null}
{
  "network": "eip155:1187947933",
  "scheme": "exact",
  "extra": {
    "name": "Bridged USDC (SKALE Bridge)",
    "version": "2",
    "chainId": 1187947933,
    "verifyingContract": "0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20"
  }
}
```

Atualmente, a SKALE fornece apenas `exact`. Se você precisar de medição posterior, use Base `upto`.

Exemplo de resultado de verificação SKALE `exact`:

```text theme={null}
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
block 1969317
explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
paid 0.095215 USDC
```

Explicação dos resultados:

* A nova tentativa de pagamento da API retorna o conteúdo do modelo `ADC_SKALE_E2E_OK`。
* A transação já pode ser consultada no explorer da SKALE, e o número do bloco é `1969317`。
* O valor de liquidação deste pagamento `exact` é `0.095215` USDC。

## Solana

Solana usa SPL USDC `TransferChecked`。O cliente constrói uma transação de transferência, assina e envia, e depois coloca a assinatura da transação ou a transação serializada no envelope `PAYMENT-SIGNATURE`。

Características do Solana：

* Usa Solana wallet adapter ou base58 secret key；
* O ativo é o mint de USDC da Solana；
* Atualmente, suporta apenas `exact`；
* O Facilitator valida o mint, destination, authority e amount da instrução de transferência。

Se for usado o modo de carteira fee payer, a carteira enviará a transação diretamente, e o Facilitator será responsável por confirmar a transação e retornar o resultado da liquidação。

Exemplo de resultado da validação `exact` do Solana：

```text theme={null}
payer AY2RmGm2zPxB1uKvvF4dKyYdr2VySyL3wcD1MKJZoLRd
HTTP 402 -> HTTP 200
content ADC_SOLANA_E2E_OK
chain signature not confirmed in this run
```

Explicação dos resultados：

* A nova tentativa de pagamento já retornou HTTP 200, e o modelo produziu `ADC_SOLANA_E2E_OK`。
* Consultas de signature on-chain via RPC público podem encontrar limitação de taxa。
* Como consultas via RPC público podem sofrer limitação de taxa, o Solana explorer não é incluído aqui。Quando for necessário reconciliar rigorosamente, use seu próprio Solana RPC ou os registros de liquidação do lado da plataforma para confirmar a assinatura da transação。

## Como escolher

| O que você quer fazer | Rede recomendada |
| - | - |
| Executar rapidamente o fluxo mínimo | SKALE `exact` ou Base `exact` |
| Voltado para usuários comuns de Web3 | Base |
| Fazer medição posterior para complementos de chat | Base `upto` |
| Aplicações do ecossistema Solana | Solana `exact` |
| Validação de pagamentos EVM de baixo custo | SKALE `exact` |

Independentemente da cadeia escolhida, não codifique o preço diretamente no cliente。O preço é determinado por `accepts[].maxAmountRequired` retornado pelo servidor。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.